Skip to content

docs: Phase 3 — hands-on environment (samples metadata, agent onboarding, navigation flow) + state-detection bug fix#3

Merged
haksungjang merged 8 commits into
mainfrom
feat/phase3-practice-env
Jun 4, 2026
Merged

docs: Phase 3 — hands-on environment (samples metadata, agent onboarding, navigation flow) + state-detection bug fix#3
haksungjang merged 8 commits into
mainfrom
feat/phase3-practice-env

Conversation

@haksungjang

@haksungjang haksungjang commented Jun 4, 2026

Copy link
Copy Markdown
Contributor

Overview

The enhancement roadmap's Phase 3 (hands-on environment). Tidies up entry metadata, onboarding, and the navigation flow so first-time owners can complete the 02→07 chain without getting stuck, and fixes a state-detection ordering bug found during review. Split into 7 chunks, with verify.sh passing 12/12 on each commit.

Changes

samples/ metadata + index

  • Added a learning-metadata table (learning goal, estimated time, difficulty, prerequisites, related chapters) at the top of three sample READMEs
  • Added a new samples/README.md index (comparison table + common prerequisites + how to use), including guidance for the path when Docker is unavailable

State-detection consistency bug fix (real bug)

  • The reader state-detection table in the root CLAUDE.md was out of order (05-analyst → vulnerability → management), inconsistent with the canonical order
  • Reordered to the canonical sequence: 05-sbom-analyst → 05-sbom-management → 05-vulnerability-analyst → 06
  • Rationale: the prerequisite for 05-vulnerability-analyst is sbom-management-plan.md (the output of 05-sbom-management), and validate-chain.py has the same dependency. Now matches agents/CLAUDE.md

Agent onboarding metadata

  • Added a one-line "estimated time" (number of questions + deliverable review time) to nine agent CLAUDE.md files. Prerequisites and the next command (copy-paste) already existed

Path for when Docker is not installed

  • Added guidance to docs/01-setup: Docker is used only in chapter 05; if it is not installed, proceed via the sample SBOM path. Chapters 02–04 and 06–07 do not need Docker

Onboarding flow (intro/README)

  • Added two honest paths (implementation agents vs. development-team tools web) and a quick-start (1–2h) / full-course (8–12h) distinction to docs/intro and README (Korean and English)
  • The no-API-key web trial is not built yet, so it is not promised and is deferred to Phase 4

Confirmed consistent (no fix needed)

  • 04-process Q5/Q6 input format: both the agent ("yes — … / no") and docs ("yes / no") already use yes/no consistently

Verification

  • Each chunk commit passed verify.sh 12/12
  • Added content is ko-style clean (existing emoji and interpuncts in untouched lines are pre-existing issues, left unmodified)

haksungjang and others added 8 commits June 4, 2026 17:27
Phase 3 실습환경 — 처음 담당자가 각 샘플의 목적·소요·난이도·선행조건을
진입 즉시 파악하도록 정비.

- samples/{java-vulnerable,python-mixed-license,nodejs-unlicensed}/README.md
  상단에 메타 표 추가(학습 목표·예상 시간·난이도·선행 조건·관련 챕터)
- samples/README.md 인덱스 신설: 3개 샘플 비교 표 + 공통 선행 조건
  (Docker 없을 때 경로 포함) + 사용 방법 3단계
- 난이도: java/python 입문, nodejs 중급(npm install 선행 필요)

verify.sh 12/12 PASS, ko-style 0건.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
루트 CLAUDE.md "독자 상태 감지" 테이블이 05-analyst→vulnerability→management
순서로 어긋나 있어 정본(agents/CLAUDE.md·validate-chain.py·05-vulnerability-analyst
전제조건)과 불일치했다.

정본 순서로 정렬: 05-sbom-analyst → 05-sbom-management → 05-vulnerability-analyst
→ 06-training-manager. sbom-management-plan.md 존재를 게이트로 사용해
agents/CLAUDE.md 상태감지 테이블과 동일하게 맞춤.

근거: 05-vulnerability-analyst 전제조건 = output/sbom/sbom-management-plan.md
(05-sbom-management 실행 후), validate-chain.py도 동일 의존성 정의.

verify.sh 12/12 PASS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Phase 3 실습환경 — agent 진입 즉시 시간 부담을 알 수 있도록 예상 소요(질문 수 +
산출물 검토 시간) 한 줄 추가. 선행조건·다음명령은 기존 섹션 유지.

- 02: 약 15분(질문 6개) / 03: 약 15분(질문 5개) / 04: 약 20분(질문 7개)

verify.sh 12/12 PASS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- 05-sbom-guide: 약 10분(질문 3개, 첫 Docker 이미지 풀링 시 +10~15분)
- 05-sbom-analyst: 약 10분(질문 2개)
- 05-sbom-management: 약 10분(질문 3개)
- 05-vulnerability-analyst: 약 10분(질문 3개)

verify.sh 12/12 PASS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- 06-training-manager: 약 10분(질문 3개) / 07-conformance-preparer: 약 15분(질문 3개)

verify.sh 12/12 PASS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Phase 3 실습환경 — Docker를 설치할 수 없는 사용자도 막히지 않도록,
도구 목록 표 직후에 안내 추가:
- Docker는 챕터 05(SBOM·취약점 실습)에서만 사용
- 설치 불가 시 챕터 05 "Docker 없이 진행" 경로로 샘플 SBOM 사용
- 02~04·06~07은 Docker 없이 agent 대화만으로 진행

(05-sbom-guide·05-sbom-generation의 Docker-없이 경로는 기존 보유, 진입점에서 연결)

verify.sh 12/12 PASS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Phase 3 실습환경 — 처음 방문자가 자신에게 맞는 경로와 시간 부담을 즉시 파악하도록
정비. 아직 존재하지 않는 기능(무API키 웹 체험)은 약속하지 않고 현재 실재하는
경로만 정직하게 제시(웹 체험 홍보는 Phase 4에서 실제 구축 후 반영).

docs/intro.md:
- "사용 경로"를 2경로 표로 재작성
  - 체계 구축(가이드+agents): OSS 관리 담당자 / 풀코스 8~12h, 빠른시작 1~2h
  - 개발팀 도구(DevSecOps·AI코딩 웹): 개발·보안팀 / 선택
- 빠른 시작(00·02·03 핵심만) vs 풀 코스(00~07 전체) 구분
- DevSecOps·AI코딩 가이드로의 크로스 인스턴스 링크(/devsecops/intro·/ai-coding/intro)

README.md(국문·영문):
- 체계 구축 경로에 빠른시작(1~2h)/풀코스(8~12h) 깊이 구분 추가
  (웹 vs Claude Code 2경로는 기존 유지)

verify.sh 12/12 PASS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- 고도화 로드맵 Phase 3 상태 ⏳ → ✅
- Phase 3 완료 내역 블록 추가(samples 메타·인덱스, 상태감지 버그 수정,
  agent 예상소요 ×9, Docker 미설치 경로, intro/README 2경로 동선)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@haksungjang haksungjang merged commit a97abed into main Jun 4, 2026
5 checks passed
@haksungjang haksungjang deleted the feat/phase3-practice-env branch June 4, 2026 08:54
@haksungjang haksungjang changed the title docs: Phase 3 — 실습환경(samples 메타·agent 온보딩·동선) + 상태감지 버그 수정 docs: Phase 3 — hands-on environment (samples metadata, agent onboarding, navigation flow) + state-detection bug fix Jun 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant